IRIX 6.5 Applications 1999 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX 6.5 Applications 1999 May / SGI IRIX 6.5 Applications 1999 May.iso / dist / arraysvcs.idb / usr / share / catman / p_man / cat3x / ascommand.z.z / ascommand.z / ascommand

Wrap

Text File | 1998-10-27 | 18KB | 331 lines

aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) NNNNAAAAMMMMEEEE ascommand - execute an array command SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>> aaaassssccccmmmmddddrrrrssssllllttttlllliiiisssstttt____tttt ****aaaassssccccoooommmmmmmmaaaannnndddd((((aaaasssssssseeeerrrrvvvveeeerrrr____tttt SSSSeeeerrrrvvvveeeerrrr,,,, aaaassssccccmmmmddddrrrreeeeqqqq____tttt ****CCCCoooommmmmmmmaaaannnndddd))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The _a_s_c_o_m_m_a_n_d function is used to execute an array command. The command request will be processed by an array services daemon. That array services daemon is responsible for translating the array command into an actual UNIX command, running it on one or more machines in the requested array, and returning the results. The SSSSeeeerrrrvvvveeeerrrr argument specifies an optional array server token, which can be used to direct the request to a specific array services daemon. If NULL is specified instead, the request will be processed by the default array services daemon (see _a_r_r_a_y(1) for more information on how the default array services daemon is selected). For more details on creating an array server token, see _a_s_o_p_e_n_s_e_r_v_e_r(3X). The CCCCoooommmmmmmmaaaannnndddd argument is a pointer to an aaaassssccccmmmmddddrrrreeeeqqqq____tttt structure (defined in <arraysvcs.h>) that describes the command request. An aaaassssccccmmmmddddrrrreeeeqqqq____tttt looks similar to this: typedef struct ascmdreq { char *array; uint32_t flags; int numargs; char **args; uint32_t ioflags; } ascmdreq_t; The aaaarrrrrrrraaaayyyy member specifies the name of the array on which the command should be executed. If aaaarrrrrrrraaaayyyy is set to NULL, the server's default destination will be used if one has been specified, otherwise the command request will be rejected. ffffllllaaaaggggssss is used to specify various control options for the command. It if formed by OR-ing together zero or more of the following values: _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_EEEE_QQQQ______LLLL_OOOO_CCCC_AAAA_LLLL Run the command on the server machine only, rather than broadcasting it to the machines in an array. If this option is specified, the aaaarrrrrrrraaaayyyy member of CCCCoooommmmmmmmaaaannnndddd will be ignored. _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_EEEE_QQQQ______NNNN_EEEE_WWWW_SSSS_EEEE_SSSS_SSSS Run the command in a new global array session. The array services daemon will allocate a new global array session handle and ensure that each machine executes the array command in an array session using this handle. PPPPaaaaggggeeee 1111 aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_EEEE_QQQQ______OOOO_UUUU_TTTT_PPPP_UUUU_TTTT Collect output from the array command. If specified, the stdout and stderr of the array command will be saved on each machine. If any output is in fact generated on a particular machine, the aaaassssccccmmmmddddrrrrsssslllltttt____tttt for that machine will contain a pathname to a temporary file containing the output. _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_EEEE_QQQQ______NNNN_OOOO_WWWW_AAAA_IIII_TTTT Ordinarily, the array services daemon will wait for the array command to complete before returning the results. If this flag is specified, the array services daemon will _n_o_t wait. The aaaassssccccmmmmddddrrrrsssslllltttt____tttt for each machine will indicate that the command has been initiated, but will not have a valid exit status for the command. _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_EEEE_QQQQ______IIII_NNNN_TTTT_EEEE_RRRR_AAAA_CCCC_TTTT_IIII_VVVV_EEEE Specifies that socket connections should be made to one or more of the command's standard I/O file descriptors (stdin, stdout and/or stderr). The exact connections to be made are specified in the iiiiooooffffllllaaaaggggssss field of CCCCoooommmmmmmmaaaannnndddd. If successful, the aaaassssccccmmmmddddrrrrsssslllltttt____tttt for each machine will contain socket descriptors for each of the requested connections. If this flag is specified, then the AAAASSSSCCCCMMMMDDDDRRRREEEEQQQQ____OOOOUUUUTTTTPPPPUUUUTTTT flag is ignored and the AAAASSSSCCCCMMMMDDDDRRRREEEEQQQQ____NNNNOOOOWWWWAAAAIIIITTTT flag is implied (i.e. an interactive request never waits for the command to complete). The iiiiooooffffllllaaaaggggssss field of CCCCoooommmmmmmmaaaannnndddd is examined only when the ffffllllaaaaggggssss field has the AAAASSSSCCCCMMMMDDDDRRRREEEEQQQQ____IIIINNNNTTTTEEEERRRRAAAACCCCTTTTIIIIVVVVEEEE flag set, and is used to indicate which of the command's standard I/O descriptors should be routed back to the caller via a socket connection. It is formed by OR-ing together one or more of the following values: _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_TTTT_DDDD_IIII_NNNN Requests a socket attached to the command's stdin. _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_TTTT_DDDD_OOOO_UUUU_TTTT Requests a socket attached to the command's stdout. _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_TTTT_DDDD_EEEE_RRRR_RRRR Requests a socket attached to the command's stderr. _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_IIII_GGGG_NNNN_AAAA_LLLL Requests a socket that can be used to deliver signals to the command (see below for details). _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______OOOO_UUUU_TTTT_EEEE_RRRR_RRRR_SSSS_HHHH_RRRR Indicates that the command's stderr should be routed back over the stdout channel. This flag is ignored if _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_TTTT_DDDD_EEEE_RRRR_RRRR is not also specified. The nnnnuuuummmmaaaarrrrggggssss and aaaarrrrggggssss members of CCCCoooommmmmmmmaaaannnndddd specify the array command itself along with any arguments. They behave similarly to the aaaarrrrggggcccc and aaaarrrrggggvvvv arguments to a standard C program. PPPPaaaaggggeeee 2222 aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) The results from each machine are summarized in aaaassssccccmmmmddddrrrrsssslllltttt____tttt structures, and a list of these structures, bundled together into an aaaassssccccmmmmddddrrrrssssllllttttlllliiiisssstttt____tttt structure, is returned by _a_s_c_o_m_m_a_n_d. Both aaaassssccccmmmmddddrrrrsssslllltttt____tttt and aaaassssccccmmmmddddrrrrssssllllttttlllliiiisssstttt____tttt are defined in <arraysvcs.h>. The storage for both structures is allocated using _m_a_l_l_o_c(3) and can be released using aaaassssffffrrrreeeeeeeeccccmmmmddddrrrrssssllllttttlllliiiisssstttt(3X). An aaaassssccccmmmmddddrrrrsssslllltttt____tttt structure looks similar to this: typedef struct ascmdrslt { char *machine; ash_t ash; uint32_t flags; aserror_t error; int status; char *outfile; /* These fields only valid if ASCMDRSLT_INTERACTIVE set */ uint32_t ioflags; int stdinfd; int stdoutfd; int stderrfd; int signalfd; } ascmdrslt_t; The mmmmaaaacccchhhhiiiinnnneeee member contains the name of the machine that generated this particular response. This is typically the network hostname of that machine, although the system administrator can override that value with a LOCAL HOSTNAME entry in the array services configuration file. The ffffllllaaaaggggssss member contains flags describing certain details about the command results. It may contain zero or more of the following values OR-ed together: _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_SSSS_LLLL_TTTT______OOOO_UUUU_TTTT_PPPP_UUUU_TTTT Indicates that the command has generated output which has been saved in a temporary file. The name of the temporary file can be found in the oooouuuuttttffffiiiilllleeee member. _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_SSSS_LLLL_TTTT______MMMM_EEEE_RRRR_GGGG_EEEE_DDDD Indicates that although the array command may have been run on more than one machine, the results were merged together by a MERGE command on the array services daemon. This aaaassssccccmmmmddddrrrrsssslllltttt____tttt describes the results of the MERGE command only. _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_SSSS_LLLL_TTTT______AAAA_SSSS_HHHH Indicates that the array command was run using a global array session handle. The array session handle itself is saved in the aaaasssshhhh member of the aaaassssccccmmmmddddrrrrsssslllltttt____tttt structure. PPPPaaaaggggeeee 3333 aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) _AAAA_SSSS_CCCC_MMMM_DDDD_RRRR_SSSS_LLLL_TTTT______IIII_NNNN_TTTT_EEEE_RRRR_AAAA_CCCC_TTTT_IIII_VVVV_EEEE Indicates that one or more connections have been established with the standard I/O file descriptors of the running command. The specific connections are described in the iiiiooooffffllllaaaaggggssss field of the aaaassssccccmmmmddddrrrrsssslllltttt____tttt structure. The eeeerrrrrrrroooorrrr member is a standard libarray error code that contains the results of the command on the particular machine. For details on libarray error codes, see _a_s_e_r_r_o_r_c_o_d_e(3X). If the "errno" subfield of eeeerrrrrrrroooorrrr is ASE_OK and the "what" field is ASOK_COMPLETED, then the ssssttttaaaattttuuuussss member will contain the final exit status of the array command's process on this machine. The iiiiooooffffllllaaaaggggssss member contains flags that describe which connections have been established with the running command. It is only valid if the AAAASSSSCCCCMMMMDDDDRRRRSSSSLLLLTTTT____IIIINNNNTTTTEEEERRRRAAAACCCCTTTTIIIIVVVVEEEE flag is set in the ffffllllaaaaggggssss member. It will contain one or more of the following values OR-ed together: _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_TTTT_DDDD_IIII_NNNN A socket connection has been established with the command's stdin. The socket descriptor is contained in the ssssttttddddiiiinnnnffffdddd member of the aaaassssccccmmmmddddrrrrsssslllltttt____tttt structure. Any data written to this descriptor will be presented to the command's stdin. _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_TTTT_DDDD_OOOO_UUUU_TTTT A socket connection has been established with the command's stdout. The socket descriptor is contained in the ssssttttddddoooouuuuttttffffdddd member of the aaaassssccccmmmmddddrrrrsssslllltttt____tttt structure. Any data that the command writes to its stdout can be read from this descriptor. _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_TTTT_DDDD_EEEE_RRRR_RRRR A socket connection has been established with the command's stderr. The socket descriptor is contained in the ssssttttddddeeeerrrrrrrrffffdddd member of the aaaassssccccmmmmddddrrrrsssslllltttt____tttt structure. Any data that the command writes to its stderr can be read from this descriptor. _AAAA_SSSS_CCCC_MMMM_DDDD_IIII_OOOO______SSSS_IIII_GGGG_NNNN_AAAA_LLLL A socket connection that can be used to deliver signals to the command has been established. The socket descriptor is contained in the ssssiiiiggggnnnnaaaallllffffdddd member of the aaaassssccccmmmmddddrrrrsssslllltttt____tttt structure. Any signal can be delivered to the running command by writing a single byte containing the desired signal number to this descriptor. Note that in some implementations, the same socket may be used to handle both the stdin and stdout connections or both the stderr and signal connections. Therefore, caution should be exercised before trying to close only one socket in either of those pairs. NNNNOOOOTTTTEEEESSSS _a_s_c_o_m_m_a_n_d is found in the library "libarray.so", and will be loaded if the option "-larray" is used with _c_c(1) or _l_d(1). PPPPaaaaggggeeee 4444 aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) aaaassssccccoooommmmmmmmaaaannnndddd((((3333xxxx)))) SSSSEEEEEEEE AAAALLLLSSSSOOOO array(1), arrayd(1M), aserrorcode(3X), asfreecmdrsltlist(3X), asopenserver(3X). DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS _a_s_c_o_m_m_a_n_d returns a pointer to an aaaassssccccmmmmddddrrrrssssllllttttlllliiiisssstttt____tttt structure if successful. If unsuccessful, _a_s_c_o_m_m_a_n_d returns NULL and sets _a_s_e_r_r_o_r_c_o_d_e appropriately. PPPPaaaaggggeeee 5555